Mobile Revoke History API

This document outlines the details of the Mobile Revoke History API.

API Description

Objective

The Mobile Revoke History API retrieves the revocation history of a given mobile number.

Input	Output
The Mobile Number	Details about: If the mobile number has been revoked The total number of times it has been revoked The chronological list of revocation dates The complete list of output fields is available in the Success Response Details section

did you know

Mobile number revocation, or more specifically, Mobile Number Revocation List (MNRL), refers to a database of permanently disconnected or deactivated mobile phone numbers. These numbers are flagged because they are no longer in use, are suspected of being involved in fraudulent activities, or have been disconnected due to various reasons.

API URL

https://ind-engine.thomas.hyperverge.co/v1/getMobileRevokeHistory

API Endpoint

getMobileRevokeHistory

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should send all data in JSON format through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Valid Values
content-type	Mandatory	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	The application ID shared by HyperVerge	Not Applicable - this is a unique value
appKey	Mandatory	The application key shared by HyperVerge	Not Applicable - this is a unique value
transactionId	Mandatory	The unique ID for the customer journey.	Not Applicable - this is a unique value related to a transaction in your application

Input

The following table provides the details of the parameter required for the API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
mobileNo	Mandatory	The 10-digit,valid mobile number	Not Applicable	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/getMobileRevokeHistory' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "mobileNo": "<Enter_the_valid_Mobile_Number>"
}'

Success Response

The following code snippet demonstrates a success response from the API:

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "revokeStatus": "Yes",
        "revokeHistory": [
            {
                "revokeDate": "<Revoke_Date_1>" // the first time the mobile number got revoked 
            },
            {
                "revokeDate": "<Revoke_Date_2>" // the next time the mobile number got revoked
            },
            {
                "revokeDate": "<Revoke_Date_3>" // the next time the mobile number got revoked
            }
        ],
        "revokeCount": 3
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code returned for the request
revokeStatus	string	The status of the revocation process ("Yes" if the number has been revoked)
revokeHistory	array	The revocation history includes the dates on which the mobile number was revoked
revokeCount	integer	The number of times the mobile number has been revoked
requestId	string	The unique identifier for the API request
transactionId	string	The transaction ID associated with the request, if available

Error Responses

The following are some error responses from the API:

Invalid Mobile Number

{
    "status": "failure",
    "statusCode": 400,
    "error": "Mobile number is invalid",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Mobile Number Not Revoked

{
    "status": "failure",
    "statusCode": 422,
    "error": "Mobile number is not revoked",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Internal Server Error

{
  "status": "failure",
  "statusCode": 500,
  "message": "Internal server error"
}

External Source Downtime

{
  "status": "failure",
  "statusCode": 503,
  "message": "External source downtime"
}

Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description
400	Mobile number is invalid	This error occurs when the mobileNo parameter is invalid or empty
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
422	Mobile number is not revoked	This error occurs when we pass a 10-digit mobile number which is not revoked
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
503	External source downtime	Please contact the HyperVerge team for resolution